/**
 * Copyright(c) 2014 Xunton Solutions
 *
 * History:
 *   15-1-10 下午3:59 Created by dwzhang
 */
package com.jade.modules.region;

import java.util.List;

import com.jade.framework.base.criterion.Criteria;
import com.jade.framework.base.util.PagingList;

/**
 * 地区管理接口。
 *
 * @author sky
 * @version 1.0 13-4-23 上午11:38
 */
public interface RegionManager
{
    /**
     * 新增一个根地区.
     *
     * @param region 新增地区
     */
    public void addRegion(Region region)
            throws RegionException;

    /**
     * 更新地区信息。
     *
     * @param region 新增地区
     */
    public void updateRegion(Region region)
            throws RegionException;

    /**
     * 移除一个或者多个地区。
     *
     * @param ids 地区标识
     */
    public void removeRegion(String... ids)
            throws RegionException;

    /**
     * 根据地区标识获取地区.
     *
     * @param id 地区标识
     */
    public Region getRegion(String id);

    /**
     * 根据名称及层级获取地区
     *
     * @param name  地区中文描述
     * @param type 地区类型
     * @return 满足条件的地区
     */
    public Region getRegionByName(String name, String type);

    /**
     * 根据名称及层级获取地区
     *
     * @param parentId 上级地区ID（可以是上一级，也可以是上面多级）
     * @param name  名称
     * @return 满足条件的地区
     */
    public Region getSubRegion(String parentId, String name);

    /**
     * 列出一个地区下面的所有子地区。仅直属子地区
     *
     * @param parentId 上级地区ID
     * @return 匹配的地区列表
     */
    public List<Region> listRegion(String parentId);

    /**
     * 列出一个地区下面的子地区，包括指定级别的子地区
     *
     * @param parentId 上级地区ID
     * @return 匹配的地区列表
     */
    public List<Region> listRegion(String parentId, int level);

    /**
     * 根据关键字查询地区信息。
     *
     * @param criteria 查询条件
     * @return 匹配的地区列表
     */
    public List<Region> listRegion(Criteria criteria);

    /**
     * 根据关键字查询地区信息。
     *
     * @param criteria 查询条件
     * @return 匹配的地区列表
     */
    public PagingList<Region> queryRegion(Criteria criteria);
}
